package net.jgrm.redisadvanced.service;

import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;

/**
 * Redis ZSet类型操作服务接口
 */
public interface RedisZSetService {

    /**
     * 向有序集合中添加一个或多个元素
     *
     * @param key   键
     * @param value 值
     * @param score 分数
     * @return 添加成功的元素数量
     */
    Boolean add(String key, Object value, double score);

    /**
     * 向有序集合中添加多个元素
     *
     * @param key          键
     * @param scoreMembers 分数和值的映射
     * @return 添加成功的元素数量
     */
    Long add(String key, Map<Object, Double> scoreMembers);

    /**
     * 获取有序集合的大小
     *
     * @param key 键
     * @return 有序集合的大小
     */
    Long size(String key);

    /**
     * 获取有序集合中指定分数范围的元素数量
     *
     * @param key 键
     * @param min 最小分数
     * @param max 最大分数
     * @return 元素数量
     */
    Long count(String key, double min, double max);

    /**
     * 为有序集合中指定元素的分数加上增量
     *
     * @param key   键
     * @param value 值
     * @param delta 增量
     * @return 增加后的分数
     */
    Double incrementScore(String key, Object value, double delta);

    /**
     * 从有序集合中移除一个或多个元素
     *
     * @param key    键
     * @param values 值
     * @return 移除成功的元素数量
     */
    Long remove(String key, Object... values);

    /**
     * 获取有序集合中指定排名范围的元素（从小到大）
     *
     * @param key   键
     * @param start 开始排名
     * @param end   结束排名
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素集合
     */
    <T> Set<T> range(String key, long start, long end, Class<T> clazz);

    /**
     * 获取有序集合中指定排名范围的元素和分数（从小到大）
     *
     * @param key   键
     * @param start 开始排名
     * @param end   结束排名
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素和分数的映射
     */
    <T> Map<T, Double> rangeWithScores(String key, long start, long end, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素（从小到大）
     *
     * @param key   键
     * @param min   最小分数
     * @param max   最大分数
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素集合
     */
    <T> Set<T> rangeByScore(String key, double min, double max, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素和分数（从小到大）
     *
     * @param key   键
     * @param min   最小分数
     * @param max   最大分数
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素和分数的映射
     */
    <T> Map<T, Double> rangeByScoreWithScores(String key, double min, double max, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素（从小到大，带偏移和限制）
     *
     * @param key    键
     * @param min    最小分数
     * @param max    最大分数
     * @param offset 偏移量
     * @param count  数量
     * @param clazz  返回值类型
     * @param <T>    返回值泛型
     * @return 元素集合
     */
    <T> Set<T> rangeByScore(String key, double min, double max, long offset, long count, Class<T> clazz);

    /**
     * 获取有序集合中指定排名范围的元素（从大到小）
     *
     * @param key   键
     * @param start 开始排名
     * @param end   结束排名
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素集合
     */
    <T> Set<T> reverseRange(String key, long start, long end, Class<T> clazz);

    /**
     * 获取有序集合中指定排名范围的元素和分数（从大到小）
     *
     * @param key   键
     * @param start 开始排名
     * @param end   结束排名
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素和分数的映射
     */
    <T> Map<T, Double> reverseRangeWithScores(String key, long start, long end, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素（从大到小）
     *
     * @param key   键
     * @param min   最小分数
     * @param max   最大分数
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素集合
     */
    <T> Set<T> reverseRangeByScore(String key, double min, double max, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素和分数（从大到小）
     *
     * @param key   键
     * @param min   最小分数
     * @param max   最大分数
     * @param clazz 返回值类型
     * @param <T>   返回值泛型
     * @return 元素和分数的映射
     */
    <T> Map<T, Double> reverseRangeByScoreWithScores(String key, double min, double max, Class<T> clazz);

    /**
     * 获取有序集合中指定分数范围的元素（从大到小，带偏移和限制）
     *
     * @param key    键
     * @param min    最小分数
     * @param max    最大分数
     * @param offset 偏移量
     * @param count  数量
     * @param clazz  返回值类型
     * @param <T>    返回值泛型
     * @return 元素集合
     */
    <T> Set<T> reverseRangeByScore(String key, double min, double max, long offset, long count, Class<T> clazz);

    /**
     * 获取有序集合中元素的排名（从小到大）
     *
     * @param key   键
     * @param value 值
     * @return 排名（从0开始）
     */
    Long rank(String key, Object value);

    /**
     * 获取有序集合中元素的排名（从大到小）
     *
     * @param key   键
     * @param value 值
     * @return 排名（从0开始）
     */
    Long reverseRank(String key, Object value);

    /**
     * 获取有序集合中元素的分数
     *
     * @param key   键
     * @param value 值
     * @return 分数
     */
    Double score(String key, Object value);

    /**
     * 移除有序集合中指定排名范围的元素
     *
     * @param key   键
     * @param start 开始排名
     * @param end   结束排名
     * @return 移除成功的元素数量
     */
    Long removeRange(String key, long start, long end);

    /**
     * 移除有序集合中指定分数范围的元素
     *
     * @param key 键
     * @param min 最小分数
     * @param max 最大分数
     * @return 移除成功的元素数量
     */
    Long removeRangeByScore(String key, double min, double max);

    /**
     * 为有序集合设置过期时间
     *
     * @param key        键
     * @param expireTime 过期时间
     * @param timeUnit   时间单位
     * @return 设置是否成功
     */
    Boolean expire(String key, long expireTime, TimeUnit timeUnit);
}